home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / gus / gusdk210.zip / README.JOY < prev    next >
Text File  |  1993-12-22  |  13KB  |  260 lines
  1.  
  2.                                            A d v a n c e d
  3.                    ▄▄▄▄  ▄▄▄▄▄    ▄▄▄▄  ▄▄    ▄▄ ▄  ▄▄▄▄▄
  4.                   ▐  ▄▄  ▐    ▌  ▐█  █▌ ▐█    █▌ █ ▐▄▄▄▄▄
  5.                   ▐    ▌ ▐▀▀█▀  ▐█    █▌ ▐█  █▌  █       ▌
  6.                    ▀▀▀▀  ▀   ▀  ▀      ▀  ▀▀▀▀   ▀  ▀▀▀▀▀
  7.                   Advanced Gravis Computer Technology Ltd.
  8. 
  9.       Fax (604) 435-9358                   BBS  (604) 431-5927 V32bis
  10.       Compuserve: GO PCVENB (71333,350)    InterNET EMail: tech@gravis.com
  11.       FidoNET: 1:153/978 or 1:153/878      SBCNET: 13:900/3
  12.       AOL: Adv Gravis                      Genie: Page M805 Topic 6
  13.  
  14.                 PC GamePad and Analog Pro SDK V1.1 (JOYSDK11.ZIP)
  15.         Copyright (C) 1993 by Advanced Gravis Computer Technology Ltd.
  16.                            All Rights Reserved
  17.  
  18.                          1.0 Installation Notes
  19.                          2.0 Support
  20.                          3.0 What is Included with this SDK
  21.                          4.0 PC GamePad and PC Analog Pro Documentation
  22.  
  23. 1.0.0 Support
  24.  -------------
  25.  Due to the low cost of the PC GamePad and Analog Pro developers toolkit
  26.  (free) we do not offer much in the way of technical support.  All the
  27.  documentation, and source code is supplied 'as is'.  We do provide a
  28.  Gravis programming message and file area on our BBS and on all the
  29.  Gravis nodes.  Please refer to GRAVNODE.TXT for more information on how
  30.  to reach us via electronic mail.
  31.  
  32. 2.0.0 What is Included with this SDK
  33.  ------------------------------------
  34.  This SDK includes:
  35.  
  36.     ■ Technical information about the PC GamePad and Analog Pro
  37.     ■ Technical information on the PC gameport
  38.     ■ Pin out for a PC gameport
  39.     ■ ASM and C routines on how to access the PC gameport
  40.  
  41. 3.0.0 PC GamePad and PC Analog Pro Documentation
  42.  ------------------------------------------------
  43.  
  44.     PC GamePad and Analog Pro Technical Notes for Software Development
  45.  
  46. Introduction
  47. ============
  48.  
  49. The PC GamePad and PC Analog Pro by Advanced Gravis Computer Technology
  50. Ltd. are position input devices for PCs and compatibles. The GamePad
  51. is a joystick-like device optimized for 'switch stick' mode games and
  52. user input applications.  While the Analog Pro is a proportional style
  53. stick built for software that require more precision, such as flight
  54. simulators. This following technical note provides a description of
  55. the GamePad and Analog Pro's hardware and software interface.  This
  56. note should assist software developers in implementing the Gravis PC
  57. GamePad and Analog Pro in their software projects.
  58.  
  59. The Analog Pro
  60. ==============
  61.  
  62. The Analog Pro behaves much like a regular analog style joystick but
  63. with a few exceptions.  First the Analog Pro comes with 5 fire buttons,
  64. while most joysticks only come with 2.  Two of these buttons can be
  65. configured to act as button 1A,1B,2A or 2B.  See table below for an
  66. explanation on how this is done. You may also refer to your joystick
  67. manual to find the defaults settings for each of the 5 buttons.
  68. Secondly the Analog Pro can use the Y-Axis of Joystick B as a throttle
  69. control. The user, by turning a dial on the Analog Pro, can change the
  70. value of this axis. It was intended to be used as a throttle control
  71. but could just as easily be used for some different purpose in your
  72. software. Below is a table explaining how to access these extra
  73. features on the Analog Pro.  Remember that only the 2 buttons on the
  74. base are selectable.  The 3 buttons on the handle are fixed.
  75.  
  76.         -- B & A               Analog Pro  Standard Gameport
  77.        ___                      ----------------------------------
  78.   C -> \ |                      X-Axis      Joystick A, X-Axis
  79.         ||       A = Button 1A  Y-Axis      Joystick A, Y-Axis
  80.    D - || - E  B = Button 2A  Throttle    Joystick B, Y-Axis
  81.      _▄_||_▄_    C = Button 1A  Button 1A   Joystick A, Button #1A
  82.      |______|                   Button 1B   Joystick A, Button #2A
  83.                                 Button 2A   Joystick B, Button #1B
  84.      Left Side                  Button 2B   Joystick B, Button #2B
  85.  
  86. The PC GamePad
  87. ==============
  88.  
  89. The PC GamePad is a device very similar to an anolog joystick.  It plugs
  90. into a standard PC gameport like a joystick.  The difference between a
  91. typical joystick and the GamePad exists mostly in the axis characteristics.
  92. Joysticks normally have X and Y axes that consist of continuously variable
  93. axis resistances, which in turn yields continuously variable X and Y
  94. positions.  The GamePad, however, provides 'fixed' resistances
  95. (non-proportional) for nine distinct GamePad controller positions
  96. (including center). The fixed resistances are set to approx. 0 ohms,
  97. approx. 50k ohms, and approx. 100k ohms.  Also, there are some differences
  98. in the buttons' arrangement. Four independant buttons are available, two
  99. of which can be configured as 'autofire' (slide switch selector).
  100. Furthermore, another slide switch allows the GamePad to be set for
  101. left-hand or right-hand use. Below is a table explaining how to read
  102. the extra buttons on the PC GamePad.
  103.  
  104.                                 PC GamePad
  105.                             4 Button   Turbo Fire  Standard Gameport
  106.    _____     ||             ----------------------------------------------
  107.   |     \____||________     X-Axis     X-Axis      Joystick A, X-Axis
  108.   |  __    GRAVIS      \    Y-Axis     Y-Axis      Joystick A, Y-Axis
  109.   | /  \  GamePad   B  |    Button A   Button A    Joystick A, Button #1A
  110.   | \__/          A   C|    Button B   Button B    Joystick A, Button #2A
  111.   |______________   D  |    Button D   Auto B      Joystick B, Button #1B
  112.                  \_____|    Button C   Auto A      Joystick B, Button #2B
  113.  
  114.  
  115. The Gameport
  116. ============
  117.  
  118. IBM defined the gameport as it exists on IBM PCs and compatibles.
  119. Their definition includes a connector spec, and a PC bus interface spec.
  120. Several PC and compatible product vendors provide gameport hardware such
  121. as multi-I/O cards, sound cards, and game cards. Some gameport hardware
  122. comes with features like computer speed compensation. For instance,
  123. Gravis makes a game card called the "Eliminator Game Card" that has
  124. speed compensation, and "UltraSound" a sound card that has a speed
  125. compensated gameport.
  126.  
  127. The portion of the gameport interface of interest to programmers is the
  128. PC bus interface. The majority of this tech note deals with the programmers
  129. interface to the gameport, with some special references to the PC GamePad
  130. and Analog Pro.
  131.  
  132. The gameport appears to the PC bus as a single read and write address at I/O
  133. address 201 hex, and is 8 bits wide. Bit 0 thru bit 3 represent the axes.
  134. Bit 4 thru bit 7 represent buttons. Button positions can be determined at
  135. any time by reading location 201 hex and testing bits 4,5,6 and 7 for
  136. high or low logic states. A high state being pressed and a low being
  137. not pressed. Because you may be dealing with micro switch style buttons
  138. you MUST DEBOUNCE in software.
  139.  
  140. Reading gameport axis information is more complex.
  141.  
  142. To gain a better grasp of the procedure for axis reading, the following
  143. discusses gameport operation.
  144.  
  145. Joystick and other postional input devices are resistive transducers.
  146. Varying an axis position causes a varying resistance.
  147. The gameport connects to one end of this varying resistance.  Within
  148. the gameport circuitry exist 'one-shot' timers (flip-flop type logic
  149. device with a resistor & capacitor time out circuit) for each of the
  150. four axes. The joystick axis resistance determines the charge up time of
  151. the capacitor. Gameport axis information is represented by capacitor charge
  152. up time, and is determined by reading the axis timer status bits at
  153. address 201 hex. The axis bits are read as high when the capacitors
  154. are charging up, and the bits go low when the capacitor charges to a
  155. pre-determined level. Thus, the high time of the axis bits directly
  156. represents the axis resistance or position. The program can input axis
  157. position information into a program by repeatatively looping and
  158. reading the axis bits while high, and counting loop iterations.
  159. The higher the loop count, the higher the axis resistance.  Note that
  160. the gameport must be written to (output any value to address 201 hex.
  161. 0 value recommended) in order to start a time out cycle.
  162.  
  163. The following psuedocode provices a simplified example of how to
  164. read an axis:
  165.  
  166.         clear loop_cout
  167.         output (0, 201h)
  168.         loop {
  169.             axis_bit = input(201h)
  170.             incr loop_count
  171.         } while (axis bit high)
  172.         return loop_count
  173.  
  174. The previous example is perhaps the simplest possible implementation of the
  175. gameport's axis reading.  Included with this package are two software
  176. examples; assembler code driver for gameport reading and C code for
  177. implementing driver and providing operator interface.
  178.  
  179. A typical gameport without speed compensation may have a time out
  180. period of approx. 1.3 millisecond for an axis resistance of 100k ohms.
  181. If you have an Apple/IBM combo stick this timeout can be as long as 2ms.  A
  182. disconnected or defective gameport would have a much greater or infinite
  183. time out period. The programmer should take this into account and limit
  184. the maximum number of axis read loop iterations to take no more than
  185. several milliseconds.  Generally, if a time out takes too long, zero
  186. should be returned.  Looping ought not continue endlessly as the computer
  187. will appear hung.  For more computer time efficiency, all axes COULD BE
  188. read CONCURRENTLY using a more sophisticated driver.  However, reading
  189. them consecutively is more reliable. The maximum times an axis needs to
  190. be read is 20/second.  10/second will work fine and you may be able to
  191. get away with 5/second.
  192.  
  193. CAUTION: The faster the machine the faster the loop count!  Hence speed
  194.          compensating gameports.
  195.  
  196. Optimizing for the PC GamePad
  197. =============================
  198.  
  199. The provided examples are for general analog joystick applications.  It is
  200. possible to find optimizations for the PC GamePad.  Optimizations are
  201. possible because each GamePad axis has only 3 typical resistances
  202. (approx. 0 ohms, approx. 50k ohms, approx. 100k ohms).  Typical
  203. joystick drivers return analog values representing axis position.
  204. The programmer would have to do 'window' comparisons of values to
  205. determine the GamePad axis positions, which could consume valuable
  206. CPU time.  A PC GamePad specific driver could handle this window or
  207. limit comparison and return data relating to the nine possible
  208. positions only.
  209.  
  210.  
  211. GamePort - PC bus
  212. =================
  213.  
  214.    Read bits at address 201 (gameport)
  215.    ===================================
  216.  
  217.    =================================
  218.    | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
  219.    =================================
  220.      |   |   |   |   |   |   |   |
  221.      |   |   |   |   |   |   |   +---- Axis       Joystick A, X-Axis
  222.      |   |   |   |   |   |   +-------- Timer      Joystick A, Y-Axis
  223.      |   |   |   |   |   +------------ Status     Joystick B, X-Axis
  224.      |   |   |   |   +---------------- Bits       Joystick B, Y-Axis
  225.      |   |   |   |
  226.      |   |   |   +-------------------- Digital    Joystick A, Button #1
  227.      |   |   +------------------------ Button     Joystick A, Button #2
  228.      |   +---------------------------- Inputs     Joystick B, Button #1
  229.      +--------------------------------            Joystick B, Button #2
  230.  
  231.  
  232.    D15 Connector
  233.    =============
  234.  
  235.                      FRONT (Female) on Gameport
  236.                      __________________________
  237.                      \ 8  7  6  5  4  3  2  1 /
  238.                       \ 9  10 11 12 13 14 15 /
  239.                        ----------------------
  240.  
  241.      Pin #  PC GamePad    PC Analog Pro     Standard Joystick
  242.     --------------------------------------------------------------
  243.       1     +5v           +5v               +5v
  244.       2     Button A      Button A          Joystick A, Button #1A
  245.       3     X-Out         X-Out             Joystick A, X-Axis
  246.       4     Gnd           Gnd               Gnd
  247.       5     N/A           N/A               Gnd
  248.       6     Y-Out         Y-Out             Joystick A, Y-Axis
  249.       7     Button B      Button B          Joystick A, Button #2A
  250.       8     N/A           N/A               +5v
  251.       9     N/A           N/A               +5v
  252.       10    Button C      Button C          Joystick B, Button #1B
  253.       11    N/A           N/A               Joystick B, X-Axis
  254.       12    Chassis Gnd   Gnd               Gnd
  255.       13    N/A           Throttle Control  Joystick B, Y-Axis
  256.       14    Button D      Button D          Joystick B, Button #2B
  257.       15    N/A           N/A               +5v
  258.  
  259.  END
  260.